Power CD

home *** CD-ROM | disk | FTP | other *** search

/ Power CD / Power CD ATARI-Rechner Lieben.iso / UTILITY / MENUDLX / BIN / GULAM.DOC next >

Wrap

Text File | 1991-08-16 | 28.8 KB | 752 lines

A Ref Manual for >> gulaam << Copyright (c) 1987 pm@Case April 1987 Gulaam is a shell (i.e., a command line interpreter) for AtariST computers. It contains some 50+ built-in commands, provides file name completion a la TENEX, has history, alias and rehash facilities, and integrates the shell with microEmacs easing the editing of commands being issued. Among the built-in commands are: egrep -- a regular expression based string pattern finder, te -- a simple terminal emulator, rx/sx -- Xmodem file transfers, and pr -- a text file printer with pagination. In common usage, it resembles csh of Unix 4.xBSD; Gulam's control structures, lexical conventions and other details are, however, quite different from csh. While I have borrowed ideas from other shells (such as Korn shell), I made no heroic attempts to be compatible with any. Where possible, I have tried to make Gulam less 'surprising' in what it does. Gulam is a free program; you are encouraged to give it to others, but at no cost. However, the source is copyrighted and will be part of a book on systems programming I am writing. The source is available on request, with the usual provisos regarding material in manuscript form. I am advised to include a disclaimer because there are unreasonable people out there. "I make no warranty with respect to this manual, or the program it describes, and disclaim any implied/explicit suggestions of usefulness for any particular purpose. Use this program only if you are willing to assume all risks, and damages, if any, arising as a result, even if it is caused by negligence or other fault." On the other hand, I know of no bug in this version (>= 04/02/87). However, I would be very surprised (and would ride on clouds for ever) if no bugs are discovered by others. Many thanks to: Jwahar R. Bammi for all the help with TOS calls, and demanding that Gulam be a 'reasonably full fledged' shell; David Conroy for writing a 'small is beautiful' microEmacs; Henry Spencer for the regexp(3) package that is now built into Gulam; David Beckmeyer for his malloc() routines; AtariST for its value to price ratio. The program was developed using Megamax and Mark Williams C compilers. Gulam Manual Table of Contents Comments on the Present Implementation ................. 2 General Usage ....................................... 2 Lexical Conventions ................................. 2 Outline of Command Processing ......................... 3 alias .............................................. 3 Batch Files ......................................... 4 Buffers: Gulam Mini and Regular Buffers ................. 4 Builtin Commands .................................... 5 cd ................................................. 5 chmod [+-w] filenames ................................ 5 Command Line Editing ................................. 5 cp filenames target-dir .............................. 6 cp filename1 filename2 ............................... 6 $cwd also $CWD ....................................... 6 date ............................................... 6 df drivenames ....................................... 6 dm ................................................. 7 dir_cache dirc ...................................... 7 dirs ............................................... 7 Dollar-substitutions ............................... 7 Dotg.g ............................................. 7 echo ............................................... 7 ef ................................................. 7 egrep .............................................. 8 endif .............................................. 8 endfor ............................................. 8 $env_style ......................................... 8 exit [number] ....................................... 8 Expressions ........................................ 8 fg ................................................. 8 File Name Completion ................................. 9 Flags .............................................. 9 foreach ............................................ 9 format ............................................. 9 gem ................................................ 9 grep/egrep/fgrep re-pattern filenames ................ 10 gulam.g ............................................ 10 Gulam Variables and Environment ....................... 11 HELP ............................................... 13 help ............................................... 13 history [-h] ........................................ 13 History Substitutions ............................... 13 $home also $HOME ..................................... 13 if ................................................. 14 IO Redirection ...................................... 14 lpr filenames ....................................... 14 ls [-lRLF] filenames ................................. 14 mem ................................................ 15 Gulam Manual Metacharacter Expansion ............................. 15 mkdir names ......................................... 15 more ............................................... 15 mv filenames target-dir .............................. 15 mv filename1 filename2 ............................... 15 mson/msoff ......................................... 16 PATH ............................................... 16 peekw and pokew ...................................... 16 popd ............................................... 16 print filenames ..................................... 16 printenv ........................................... 17 $prompt ............................................ 17 pushd [dir] ......................................... 17 pwd ................................................ 17 Query Search/Replace ................................ 17 Regular Expressions ................................. 18 rehash ............................................. 19 ren fnm1 fnm2 ........................................ 19 rm filenames ........................................ 19 set [name value] ..................................... 20 setenv ............................................. 20 source file-name .................................... 20 status ............................................. 20 Strings ............................................ 20 sx ................................................. 21 te/teexit .......................................... 21 Tenex File Name Completion ............................ 21 time [command] ...................................... 21 touch fnms .......................................... 22 ue [-r] [fnms] ....................................... 22 uekb redefine microEmacs keybindings .................. 22 unalias [aliassed-name] ............................. 25 unset [var-name] .................................... 25 unsetenv [env-var] .................................. 25 variables .......................................... 25 which .............................................. 26 while .............................................. 26 Comments on Gulam Manual 2 >> Comments on the Present Implementation << The present implementation (dated 03/31/87) is incomplete. However, I find it eminently useable, and indeed use it all the time, in preference to other shells. I am at a stage where I feel further effort in this program should be predicated on how useful other people find this program; so, please tell me both the good and bad things about it. Here are some features that I find unsatisfactory. Control structures are quite ad-hoc, and incomplete. I had a tough time in decreeing that the typical "+-*/()[]{}" are not delimiters; but that decision made Gulam smaller. Here are some things that I hope to add in the months to come: Procedures (with call by name?), keyboard macros available everywhere, and local editing of remote files (this is the real reason why rx/sx are built-in) with transparent transfer of portions of the file. There are a couple of people here who are thinking if they have the time to port this program to Unix and MS-DOS; I think it will be quite routine. >> General Usage << The syntactic details of individual commands, and the sepcific rules that are followed in evaluating them are given later. This section is an overview of how the integration of ue with a shell is used. The moment you enter Gulam, you are in a ue-buffer called >mini<. Thus, all the typical ue text-editing functions are available, except commands such as Visit-file, Switch-to-buffer, etc. The -return- key causes the entire line (on which the return is typed) to be evaluated. The output, if any, of the command you issued appears on the screen but does not enter any ue-buffer. The built-in command "ue" (without any arguments) takes you into the special ue-buffer named >gulam<; the output of (built-in) commands issued while you are in >gulam< does enter that buffer, which can be freely edited. The command "ue <filenames>" will read-in each of the named files into their ue-buffers. From within "ue", you can Switch-to-Gulam-buffer (whose default binding is ESC-g). To conserve/manage memory, we release all uE buffers when uE is exited in the usual way (i.e., UNDO, or ^X-^C); exiting temporarily via the ^Z does not release memory. Lexical Conventions Gulam Manual 3 >> Lexical Conventions << All input to Gulam is case-sensitive; on the other hand, TOS file names are case-independent. The evaluation of the command line begins by dividing it into -words- and -subwords-. The word-delimiters are: space tab return line-feed (the so-called white chars) single-quote double-quote semicolon vertical-bar Note that +-*=/()[]{} etc. are *not* word-delimiters. A word is either (1) a sequence of chars not containing any word-delimiters, (2) a string of arbitrary chars enclosed in single/double-quotes, (3) a semicolon, or (4) a vertical-bar. Eg, the lines below date 01-22-87-22:08:34 #sets the TOS and ikbd date and time alias cl 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .; linkmm l.lnk' if {$x + $y ==23 } if { -e $1.c } would be divided into the words (shown between slashes) /date/01-22-87-22:08:34/#sets/the/TOS/and/ikbd/date/and/time/ /alias/cl/'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .; linkmm l.lnk'/ /if/{$x/+/$y/==23/}/ /if/{/-e/$1.c/}/ Comments begin with a word whose first char is #, and end at the end of line. A # embedded in the middle of a word does not begin a comment. The subword-delimiters are the chars in "!@#$%^&-=+`~{}:;'"\|,.<>/" >> Outline of Command Processing << The command line is string pre-processed as described below before invoking it as a command. (1) History substitutions occur first; (2) Dollar substitutions, wiggle expansion, meta expansions occur second; (3) Split the resulting line into semi-colon separated commands, (4) For each command, alias expand it, and dollar-substitute; (5) Execute each resulting command. alias Gulam Manual 4 >> alias << The 'alias' built-in command works almost like a shell file but one that is stored in the internal data structures of Gulam. It often just specifies a shorter or different name for a command. alias cc c:\megamax\mmcc.ttp #1 unalias cc #2 alias cl 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .; linkmm l.lnk' #3 alias r 'echo $1.c $1.o; r' #4 alias #5 alias g 'echo $3 $1' #6 alias cg 'f:\cc.ttp -c -V -Ie:\gulam -DMWC e:\gulam\$1.c' #7 Alias without args (see #5) lists all the aliases that are currently defined. The command unalias (see 2) removes the def of an alias. Line 4 shows a recursive def; try it out! If we invoke g as in 'g a b c d e f' this is equivalent to 'echo c a d e f'; i.e., all arguments above the highest that was used in a $-substitution are appended to the resulting command string before executing it. >> Batch Files << A batch file, also called a shell file, is a text file containing Gulam commands, both internal and external. Such files must have the extension `.g' for them to be recognized as commands. See the section on gulam.g for an example shell file. In processing these files Gulam uses uE buffers. So, if you have `ue' as a command in a batch file, and then exit uE with either UNDO or ^X-^C, all the buffers (including the one holding the batch file) will be released, and Gulam will surely crash. So, do NOT include ue as a command in a shell file. >> Buffers: Gulam Mini and Regular Buffers << Once you invoke Gulam, you are always in one of the microEmacs `buffers' which are reservoirs of text. In this program, a typical line-oriented command shell is integrated with microEmacs. This necessitated two special kinds of buffers, named >gulam< and >mini<, along with the regular buffers. Right after you invoke gulam, you are in >mini<, and each line you type is taken as a Gulam command, and executed. Any output produced by such a command is displayed on the screen but not entered into any microEmacs buffer. Should you desire to capture such output into a buffer, enter the >gulam< buffer by typing `ue' without any arguments. If you are editing in a regular buffer elsewhere in microEmacs, pressing ESC-g (see uekb below for switch-to-Gulam-buffer) will get you into >gulam<. Buffers: Gulam Gulam Manual 5 While you are in >gulam<, the RETURN key behaves as it does in >mini<. All command input, including giving the names of buffers within ue, takes place in >mini<. The window for this buffer is always at the bottom of screen, and usually only one-line high. (Some of you may want to experiment with ^X-^Z and ^X-z.) You enter the >mini< either because (A) you are outside the normal microEmacs, or (B) a command such as Switch-to-buffer wants to read your input. The >mini< is like any other buffer except for the bindings of a few keys, and the disallowing of ue functions that change/switch buffers/windows/files. One of these exceptional keys (in >mini<) is the RETURN key: it will submit the entire line -- even if the cursor was somewhere in the middle of the line-- to the shell (case A), or to such ue commands as Visit-File (case B). Until you press RETURN, you can edit not only that line but others in >mini< just as you would in regular buffers. Note that unless you occasionally exit microEmacs with ^X-^C or UNDO, both >gulam< and >mini< buffers will keep growing, and you may run out of memory. >> Builtin Commands << A command executed directly by the shell is called a built-in command. The 61 built-in commands of Gulam are: alias dirc exit history msoff pwd source unalias cd dirs fg if mv rehash sx unset chmod echo fgrep lpr peekw ren te unsetenv copy egrep foreach ls pokew rm teexit which cp ef format mem popd rmdir time while date endfor gem mkdir print rx touch df endif grep more printenv set ue dm endwhile help mson pushd setenv uekb >> cd << The cd command changes the current working directory; it also sets the shell variable named cwd, the environment variable named CWD. If cd was given noarguments, it is equivalent to cd $home. >> chmod [+-w] filenames << The chmod changes the read/write attributes of the files: +w makes them read-write, and -w makes them read-only. Command Line Gulam Manual 6 >> Command Line Editing << Full microEmacs editing is available while typing the command. Thus, you can transopse chars by ^T, and go to the beginning of the line by ^A, and ^yank in a perviously deleted word, etc. In addition to these, there are three convenience features. After typing the first few chars of a file name, if you press the key marked INSERT, Gulam will attempt to complete the file name; pressing CLR/HOME will show all possible completions. Secondly, if you type !n and then press INSERT, you will see that the history-expanded result is brought into the buffer, which can then be further edited if necessary. Thirdly, pressing the DownArrow key will cycle you through the previous commands. >> cp filenames target-dir << >> cp filename1 filename2 << Copies files. In the first form, any number of files may be copied into the destination directory; files in the target dir will have their original names. In the second form, only one file is copied, and the new one will be named filename2. cp fnm fnm # will exit with status -1 cp d1 dir2 # if d1 is a directory, this command will createa dir # named d1 in dir2, and copies all the files in d1 to to # dir2\d1 There is a `+t' option that gives the created target files the time and date of the source files. If you care about this, you may want to set up an alias as in: alias cp 'cp +t' >> $cwd also $CWD << The shell variable named cwd (and env var named CWD) holds the full path name of the current working directory. >> date << The date command, without arguments, prints the current date and time. With arguments, it sets the date and time. date 01-22-87-22:08:34 will set the date to Jan 22, 87 and time to 10:08:34 pm. df drivenames Gulam Manual 7 >> df drivenames << Df shows the free space on the asked for drive(s); e.g., 'df a c f' >> dm << -- drive map Gives a string of letters that stand for the installed drives. >> dir_cache dirc << To help do the Tenex file name completion efficiently, there is a cache of contents of directories. Dirc shows the names of these dirs, and how many bytes are used by their contents. Unless you did a 'set dir_cache 1', the dirc has nothing to show since the cache is flushed at the end of each command. Try Gulam with dir_cache set to 1. Note however that this cache is updated only by the 'ls' command; so even after you deleted some files, file name completion may still find those names. >> dirs << Gulam has an internal stack of directories whose content is printed by the dirs command. The built-in commands pushd, and popd are the only others that operate on this stack. >> Dollar-substitutions << The subword $x in a command is substituted by the value of it. If x is the name of a shell var, or an environment var, then $x is the value of that variable. If x is an unsigned number, it stands for the x-th argument; thus, $0 usually gives the command name. $* stands for the text of the entire command; $- stands for words $1 to dollar-last; $< stands for the on-demand input given by the user. >> Dotg.g << -- see Batch Files, and gulam.g >> echo << The echo command prints its arguments. ef Gulam Manual 8 >> ef << -- see if (stands for elseif) >> egrep << -- see grep >> endif << -- see if >> endfor << -- see foreach >> $env_style << This shell var controls the format of the environment string supplied to the external command invoked through Gulam. set env_style bm # to get a style of env string a la Beckmeyer set env_style mw # Mark Williams set env_style gu # the "normal" style, a la Unix >> exit [number] << The exit built-in command is used to force termination of a shell script >> Expressions << An atomic exp is either a number, a filename, a file predicate, a '{ exp }', or '! atomic exp'. A file predicate on a file name fnm is of the form '-c fnm' where c is in {e, f, d, h, v, m}. These letters stand for exists, is-a-regular-file, is-a-dir, is-a-hidden-file, is-a-volume-label, and is-an-archived-file. A filepred yields 1 if it is true, 0 otherwise. An arithmetic expression is constructed using the operators +-/%* All these are of equal precedence and evaluated left-to-right; thus, 2 + 4 / 2 is equal to 3. However, the braces raise the precedence of the ops within them; thus, 2 + { 6 / 2 } is equal to 5. An exp with no operators, i.e., an atom, is a special case because we want the string form of the atom (e.g., as for "blah" in "set s blah"). A non-numeric string yields 0 as its numeric value in an arith exp. A relational expression is of the form `arithexp relation arithexp', where relation is any one of <=, <, ==, !=, >, or >=. Such a relation yields a 1 if it holds, 0 otherwise. (Relational operators among strings are not implemented yet.) You may combine expressions using the boolean operators && and || (which are not, for now, short-circuit evaluated). Note the spaces in the examples above; see Lexical Structure. fg Gulam Manual 9 >> fg << Fg is part of the simulation of what we were used to doing on Unix with GNU-Emacs: get out of it by stopping GNU (^Z in ue/Gulam), do a few shell commands and get back in by fg (works the same in ue/Gulam). >> File Name Completion << -- see Tenex ... >> Flags << Most commands (built-in or external) take flags to alter the behavior of the command in a minor way. The convention made popular by Unix shells is adopted here for Gulam's built-ins: a flag is of the form `-c', or `+c', where c stands for one character. The option '-i', which interrogates you for each of the operand of the command before executing it, is provided on most commands. >> foreach << The foreach command is used in shell scripts (but not at the terminal) to specify repetition of a sequence of commands while the value of a certain shell variable ranges through a specified list. The foreach command ends with an "enfdor" on a separate line all by itself. foreach i { a b c *.o [a-k]*[ch] } echo $i endfor >> format << This command formats diskettes, in the standard form (360K, or 720K) in either the A or B floppy drive. It does not touch hard-/ram-disks, no matter what arguments (illegal or not) you give it. Its valid arguments are either `a', `b', or both. The optional flag `-2' implies double-sided formatting; otherwise the diskette is formatted single-sided. format # does nothing format b # format the floppy in drive B, single-sided format -1 b # same as format b format -2 a # format the floppy in drive A, double-sided If you issue the wrong command (e.g., `format -2 a' on a single-sided drive), you will hear a lot of grinding noises; a control-C will kill this, but not right away. gem Gulam Manual 10 >> gem << The word "gem" is a prefix, like "time" is, to commands. This enables proper running via Gulam of most programs that use the desktop metaphor. It clears screen, turns cursor off, enables mouse and then executes the command, and after the command is finished it again clears screen, turns cursor on, disables mouse. The "time" and "gem" prefixes mix in either order, and the command name will be searched for in the usual way. We do not know, for sure, if all desktop/window/mouse oriented programs can be run properly with this command prefix. So experiment, and be ready to hit the reset button before using the prefix. Dvi is an example of a command that needs to be run with `gem' prefix. And you may be tempted to do the following. alias dvi 'gem dvi' # recurses infinitely alias dzz dvi # dzz or whatever alias dvi 'gem dzz' # will work alias dvi 'gem c:\bin\dvi.prg' # also will work >> grep/egrep/fgrep re-pattern filenames << The grep command searches through a list of argument files for a specified string. Thus grep lex[aw] e:\gulam\*.c will print each line in the files that contains a substring matching lex[aw]. Grep stands for `globally find regular expression matches and print'. Grep and egrep are one and the same. The first argument to egrep is a regular expression, and the rest are expected to be file names. Fgrep's first argument is the as-is string to be searched for in the files. Because of the preprocessing done by Gulam, the as-is string for fgrep or the regular exp for egrep is generally enclosed in single-quotes. >> gulam.g << Files with the .g extension are expected to contain Gulam commands; gulam.g is the name of the startup file. Gulam attempts to find this file in the current directory, and if found executes its contents. Here is an example file: gulam.g Gulam Manual 11 # bgn of my gulam.g set prompt '$ncmd $cwd gu > $u' set histfile e:\history.g set baud_rate 9600 set sz_rs232_buffer 4096 set rgb '005-707-070-075-' # set the palette; note the trailing '-' # the following sets tabs on Epson MX-80 set pr_bof '^Q033^QD^Q010^Q020^Q030^Q040^Q050^Q060^Q070^Q033^QC^Q102' set pr_eof '^Q214' set pr_eop '^Q214^Qn' set pr_eol '^Qr^Qn' setenv PATH c:\bin,d:\bin,f: # no trailing back slashes rehash setenv TEMP f:\ alias h history alias ll ls -lF alias p more alias rm rm -i # asks before deleting alias ug 'ue e:\gulam\$1.c' alias cg 'f:\cc.ttp -c -V -O -Ie:\gulam -Ie:\ue -DMWC e:\gulam\$1.c' alias cpall 'cp e:\ue\*.o e:\gulam*.o f:\ ' alias bk 'cp e:\ue\*.[ch] e:\gulam\*.[ch] e:\gulam\mwc.s a:\ ' # end of my gulam.g Gulam Variables Gulam Manual 12 >> Gulam Variables and Environment << The following shell variables cause/control useful effects. The format of the explanation is `variable_name: default-value; meaning'. batch_max_nesting: 20; if you need to nest batch file execution at levels deeper than this, change this variable. batch_echo: 0; if 1 echoes each cmd of the batch file as it is executed. baud_rate:none; for use in the terminal emulator, rx/sx file transfers. cwd:CWD: full pathname of current directory; gets re-set every time a cd, pushd or popd is executed. dir_cache: 0; (if non-0, turns on the dir list cache) home,HOME: full pathname